org.globalplatform Documentation Differences

This file contains all the changes in documentation in the package org.globalplatform as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

This interface defines thea method through which an Application may forward input data to another Application.

This interface thatshall representsbe implemented by an applet method accessible throughApplication that wishes to thereceive personalization OPEN to thedata forwarded by application'sits associated Security Domain. This interfaceIn must besuch a implementedscenario, byif the Applet Application class that willimplements both the useApplication theand the additionalPersonalization functionalityinterface, allowing athen the Security Domain to pass datashall touse the appletPersonalization interface.

@see Personalization @since export file version 1.0

ThisProcesses method processes application specific data received from another entity on the -card entity.

If this other entity is thethe Application invoking this method Application'sis associateda Security Domain, thisthen datait shall be assumed that:

• The baBuffer byte array is the a global APDUbyte buffer.array; Notes:
• DuringThe the invocation the Java Card VM performsdata forwarded by the Security Domain is a contextSTORE switchDATA command. TheThe applicationsOffset is responsible forparameter locates the managingclass byte of the command and the sLength parameter indicates the atomicitylength of itsthe ownentire command (i.e. header + data field).
• AsAny exception thrown by this method canwill be invokedrethrown by a Securitythe Security Domain, immaterialhence ofwill be converted to and returned as a response status word to the Applicationoff-card Life entity. CycleIf State,the itexception is an ISOException, then the responsibilitystatus ofword will be the applet to ensurereason code of that itsexception. currentOtherwise, Life Cycle State isa status word of valid'6F00' forwill be returned.

Notes:

• Upon invocation of this operationmethod, the Java Card VM performs a context switch.
• As the appletApplication is not the currently selected applicationApplication, itit should not useattempt to access transient memory of the type CLEAR_ON_DESELECT whenduring creatingthe transientprocessing of this arraysmethod.
• If the method throws anThe Application is responsible for ISOExceptionmanaging the JavaCard runtime environment sends atomic modification of its own thedata, associatedif reasonneeded. code
• As as the response statusthis method may be instead. invoked If the Exception thrown does not extendsby a Security Domain immaterial of the ISOExceptionApplication's internal state, the reason code usApplication is responsible ISO7816.SW_UNKNOWN.for ensuring Thethat its internal state personalizationis valid session remains openfor this operation.

@param baBuffer the source byte array containing theinput data. expected by theMust be a appletglobal byte array. This@param buffersOffset must beoffset globalof input data within baBuffer. @param sOffsetsLength starting offsetlength of input data. within@exception SecurityException if baBuffer sourceis not a global byte array. @param sLengthexception NullPointerException lengthif baBuffer is null. @exception ArrayIndexOutOfBoundsException if reading input data would cause access of data outside array bounds.

This interface provides services to recoverallows performing operations such aas recovering a cryptographic key and toor signsigning data. The CASD shall publish this interface to the OPEN, using Global Service interface, to make itsrequired services available to other Applicationsalgorithms and credentials are known implicitly. The

APSDIt is theintended first entity requiring this service from the CASD asthat Security Domains would be able to access an shownAuthority ininstance 2.1. through There is only one CASD inside thea Global Service by a Controlling Authority card.Security TheDomain (CASD shall register this service) aswith a unique Global Service with the service family identifiername =#83#of (per section GPSystem.FAMILY_AUTHORITY<8.1.3 of GlobalPlatform Card Specification v2.2|0x00).

The Authority interface is responsible@since for

signing
• export and verifyingfile version message1.2: withinitial aversion. key
• export implicitly knownfile version 1.6: Thereviewed overall implementerdescription of this interface has the knowledge of the keys used for the different operations. @since export file version 1.2

Initializes the Authority interface with the appropriate mode (MODE_SIGN or MODE_KEY_RECOVERY). @param theMode one of .MODE_SIGN or .MODE_KEY_RECOVERY . @exception CryptoException with the following reason code:

• ILLEGUAL_VALUE if theMode option is an undefinedundefined value.

Recovers a cryptographic key from a set of data structures provided in the input buffer (inBuff). As a mandatory step, the recovery mechanism includes the verification of the origin and integrity of the recovered key. This method knows, from the set of data structures present in the input buffer, which recovery mechanism is to be used. The recovered key is written in the ouput buffer (outBuff) at specified offset (outOffset), in the form of a key data structure whose format depends on the type of the key. A call to this method resets this instance of the Authority interface to the state it was in when previously initialized via a call to init(). That is, the object is reset and available to recover another key. The input and output buffers may overlap and shall be global arrays. @param inBuff containing input data. @param inOffset offset of input data. @param inLength length of input data. @param outBuff the buffer where recovered key data structure shall be written @param outOffset offset where recovered key data structure shall be written @return Length of the recovered key data structure written in outBuff at outOffset,or 0 if the recovery mechanism failed (e.g. recovered key was considered invalid). @throws CryptoException - with the following reason codes:

• INVALID_INIT if this Authority interface is not initialized or initializedinitialized in MODE_SIGN mode.

@throws SecurityException if the inBuff or outBuff are not global arrayarrays.

Generates the signature of all/last input data. A call to this method resets this Authority interface to the state it was in when previously initialized via a call to init(). That is, the object is reset and available to sign another message. The input and output buffer may overlap and shall be global arrays. @param inBuff the input buffer of data to be signed @param inOffset the offset in input buffer at which the signature starts @param inLength the byte length to sign @param sigBuff the output buffer to store signature data @param sigOffset the offset into sigBuff at which to begin signature generation @return the number of bytes of signature output in sigBuff @throws CryptoException with the following reason codes:

• INVALID_INIT if this Authority interface is not initialized or initialized in MODE_KEY_RECOVERY mode.
• ILLEGAL_USE if this Authority algorithm does not pad the message and the message is not block aligned.

@throws SecurityException if the inBuff or sigBuff are not global arrayarrays.

Accumulates input data. for the current operation (MODE_SIGN or MODE_KEY_RECOVERY).

When this method is used, temporary storage of intermediate results is required. This method should only be used if all the input data required for the current operation is not available in one byte array. The sign or recoverKey methods are recommended whenever possible. The inBuff shall be global array. @param inBuff buffer containing input data @param inOffset offset of input data @param inLength length of input data @throws CryptoException with the following reason codes:

• INVALID_INIT if this Authority interface is not initialized.

@throws SecurityException if the inBuff is not global array.

Used inwith .init() methodsmethod to indicate key recovery mode.

Used inwith .init() methodsmethod to indicate signature signsigning mode.

This interface defines thebasic interfaceCardholder Verification Method services (e.g. comparison of CVM value, CVM state query). It is typically exposed to on-card Applications by a Global Services Application implementing one oror more Cardholder Verification MethodsMethods. ThisSome services class offers basic Cardholder Verification Method servicesare restricted to Applications having the CVM (eManagement Privilege.g

To retrieve an instance of this interface, an Application shall invoke the GPSystem.getCVM method, or shall use a GlobalService instance of the GPSystem.FAMILY_CVM family. For verificationbackward compatibility, the CVM stateinstances interrogation)retrieved tousing anythe GPSystem.getCVM method are mapped onto those retrieved as Global Services of the ApplicationsGPSystem.FAMILY_CVM family.

presentThe onCVM instance maintains the cardfollowing data (see Card Specification v2.2.1 section 8.2.2 for more details):

• CVM state: ACTIVE, INVALID_SUBMISSION, while someVALIDATED or ofBLOCKED. In addition, we distinguish the servicescase where the CVM instance is not fully initialized (ei.ge. unblockeither the CVM, change CVMvalue or valuethe CVM try limit has not been set) are restricted to Applicationsand has never entered withthe state ACTIVE.
• CVM try limit: the privilege to changemaximum value of the CVM valuestry counter. Prior
• CVM totry usingcounter: thisthe interface, annumber Application is required to obtain a handle toof unsuccessful comparisons of the CVM value that themay be performed before this CVM servicesinstance gets blocked. The
• CVM value: the secret value held by this CVM applicationinstance, shall exposestored in theASCII, BCD or HEX format.

Operations performed by GlobalServicethis interface objectshall be independent of, and not interfere with, any transaction in progress (s)e.g. if throughthe applet.getShareableInterfaceObject()verify accordingmethod tois invoked from within a transaction and this specification.transaction is aborted, then the try counter is not revert to its original value).

@since

• export file version 1.0: initial version.
• export file version 1.6: reviewed overall description of this interface.

ThisSets the CVM state to BLOCKED.

If the Application invoking this method setsdoes not have the CVM Management Privilege, then the CVM state is not updated.

The CVM state can only be set to BLOCKED if the CVM instance already entered the state ACTIVE once, that is, if the CVM instance is fully initialized. Notice that this method shall return true if the CVM state is already BLOCKED.

Notes:

• The CVM application shall verify the CVM Management privilege usingIf the Global Service Application providing this CVM instance has the GPRegistryEntryGlobal interfaceRegistry Privilege, it is ofable to check that the Application invoking applet. this method has the CVM Management Privilege using the GPRegistryEntry interface;

@return true if the CVM state was set to BLOCKED, false otherwise. @see GPRegistryEntry#PRIVILEGE_CVM_MANAGEMENT

ThisGets method returns the number ofCVM try triescounter, remainingthat foris, the CVM. Thisnumber indicates the numberof unsuccessful comparisons of times the CVM value canthat may be incorrectly presented prior to the CVMperformed before this CVM instance gets reachingblocked.

the@return statecurrent value of BLOCKED. the @returnCVM Tries remainingtry counter.

ThisIndicates method indicates whether thethis CVM instance is active, that is, whether it has been fully presentinitialized (i.e. both value and try limit) and activatedis ready for use. If activeyes, then the CVM couldstate is deemed to be in any one of thethe following states: ACTIVE, INVALID_SUBMISSION, VALIDATED or BLOCKED.

@return true if the CVM state ishas been (atfully least)initialized ACTIVEand is ready for use, false otherwise (i.e. the CVM state is NOT_READY).

ThisIndicates methodwhether this CVM instance is blocked, indicatesthat is, whether the CVM is currentlyCVM state is BLOCKED.

@return true if the CVM state is BLOCKED, false otherwise.

ThisIndicates method indicates whether an attempt has been made to compare the CVM value. Note: This method does, notthat differentiateis, whether the CVM value has beenstate successfully is verifiedINVALID_SUBMISSION or not, i.e. CVM states of VALIDATED or INVALID_SUBMISSION.

@return true if the CVM state is (atINVALID_SUBMISSION least)or SUBMITTEDVALIDATED, false otherwise.

ThisIndicates method indicates whether a successful comparison of the CVM value has occurred, that is, whether the (CVM state ofstate is VALIDATED).

@return true if the CVM state is VALIDATED, false otherwise.

ThisResets the CVM state to ACTIVE, even if it is currently BLOCKED.

If the Application invoking this method resetsdoes not have the CVM Management Privilege, then the CVM state fromis BLOCKEDnot updated.

The CVM state can only be set to ACTIVE. Notes: if Thethe CVM Application shall verifyinstance already entered the state ACTIVE once, that is, if the CVM Management privilege usinginstance is fully initialized. If the GPRegistryEntryCVM interfacestate is successfully reset, then this method also resets the CVM try counter ofto the invokingCVM applet;try limit.

Notes:

• TheIf the Global Service Application providing this CVM tryinstance counterhas the Global Registry Privilege, it is resetable to check that the Application wheninvoking this method unblockinghas the CVM. Management Privilege using the GPRegistryEntry interface;

@return true if the CVM state was reset to ACTIVE, false otherwise. @see GPRegistryEntry#PRIVILEGE_CVM_MANAGEMENT

ThisResets method resets the CVM state to ACTIVE.

Notes: The state of the CVM state can only be setreset to ACTIVE from the states ACTIVE, INVALID_SUBMISSION or VALIDATED. TheIn particular, it cannot be reset to ACTIVE if it is in state ofBLOCKED or if the CVM cannot be set toinstance never entered the state ACTIVE, fromthat BLOCKED. is, if the CVM instance is not fully initialized.

@return true if the CVM state was reset, false otherwise.

This methodSets the setsCVM try limit, that is, the maximum numbervalue of tries for the CVM. try counter.

Notes: TheIf CVMthe Application shallinvoking this method does not verifyhave the CVM Management privilegeManagement usingPrivilege, then the GPRegistryEntryCVM interface of the invokingtry limit is not applet; set.

TheIf the CVM try counterlimit is resetsuccessfully when settingset, the maximum number ofthen this method also tries; resets Thethe CVM state istry resetcounter to ACTIVEthe new whenCVM try limit. changingIf the maximumCVM number ofvalue has tries. already When setting thebeen successfully set maximumpreviously, number ofthen this triesmethod also before(re)sets the CVMCVM state isto ACTIVE,.

Notes:

• If the Global Service Application providing this CVM stateinstance has the Global Registry Privilege, it is transitionsable to ACTIVEcheck onlythat ifthe Application invoking this method has the CVM value is alreadyManagement Privilege using set. the GPRegistryEntry interface;

@param bTryLimit the maximum number of tries for the CVM. @return true if the maximum number oftry trieslimit was set, false otherwise. @see GPRegistryEntry#PRIVILEGE_CVM_MANAGEMENT

ThisUpdates method changes the CVM value.

Notes: TheIf CVMthe Application shall verifyinvoking the CVM Management privilege usingthis method does not have the GPRegistryEntryCVM interfaceManagement ofPrivilege, the invokingor if applet; the Thespecified invokingformat applet(bFormat) is responsible for specifying the formatunknown of(or the CVMnot supported value; by Thethis CVM Retry Counter is resetinstance), when changingor if the new CVM value; Theis CVM state is resetnot consistent with respect to ACTIVEthe specified whenformat, changingthen the CVM value. is not updated.

When setting If the CVM value before the CVMis state issuccessfully updated ACTIVE,and the CVM state transitions to ACTIVE only iftry limit has already been successfully set thepreviously, Retry Limit is alreadythen this method also set; resets the DataCVM presented always replacestry counter to the previous dataCVM regardlesstry oflimit, itsand format(re)sets orthe CVM length.state Theto CVMACTIVE.

shallNotes:

remember
• If the format, length,Global and value of theService Application providing this CVM data. instance The CVM mayhas the Global (orRegistry Privilege, mayit not)is do editing checks onable to check that the dataApplication andinvoking this method rejecthas the CVM updateManagement if the dataPrivilege using the failsGPRegistryEntry theinterface; editing
• The checksCVM (e.g.instance reject data thatshall record the isformat, presentedlength, as BCD that is notand value of the CVM numerical)value.

@param baBuffer the source byte array containing the new CVM value. This bufferMust must be a global byte array. @param sOffset the offset of the new CVM value within source byte arraybaBuffer. @param bLength the length of the new CVM value. @param bFormat the format of the new CVM value: . FORMAT_ASCII, .FORMAT_BCD or .FORMAT_HEX. @return true if the CVM value was changedsuccessfully updated, false otherwise. @see GPRegistryEntry#PRIVILEGE_CVM_MANAGEMENT @exception SecurityException if baBuffer is not a global byte array. @exception NullPointerException if baBuffer is null. @exception ArrayIndexOutOfBoundsException if reading the new CVM value would cause access of data outside array bounds.

ThisCompares methoda value compareswith the stored CVM value.

withIf the oneCVM passed asstate is parameter. BLOCKED, Notes: or Ifif the value passedsubmitted asformat parameter(bFormat) is not inunknown the(or same format as thenot supported by this CVM valueinstance), the value passed as parameter mustor if this method throws a beNullPointerException converted prioror an toArrayIndexOutOfBoundsException, comparingthen the comparison is deemed unsuccessful.

If HEXthe formatsubmitted CVM value is presented for CVM verification and ASCII or BCDnot in the same format as the stored CVM value, then format was used for updatingconversion shall occur according to the CVMfollowing value,rules the comparisonprior to fails; comparing values:

• If HEX format is presented for CVM verificationsubmitted and HEX format was used for updating the CVM valuethe stored CVM value is in ASCII or BCD format, the comparisonthen succeeds when the lengththe conversion cannot occur and the datacomparison value match exactlyis deemed unsuccessful;
• If BCD or ASCII format is presented forsubmitted CVM verification and HEX format was used and the stored CVM value is in HEX forformat, updatingthen the CVMconversion value,cannot occur and the comparison failsis deemed unsuccessful;
• If ASCII format is presentedsubmitted and the forstored CVM verificationvalue andis BCDin BCD format, was used for updatingthen conversion can occur if the submitted CVM value, the comparison failsonly contains numerical ifASCII characters: the ASCIInumeric characters presented(coded foron one verificationbyte) are not all numericalof the submitted value (zeroare converted to nine).numeric nibbles, If all thepadded together in ASCIIbytes, characters areand a numerical,padding formatnibble conversion'F' is occurs andadded on the comparisonright succeeds if necessary. whenOtherwise, the lengthconversion cannot occur and the data value match exactlycomparison is deemed unsuccessful;
• If BCD format is presentedsubmitted and the forstored CVM verificationvalue andis ASCIIin ASCII format, was used for then conversion can occur updatingif the stored CVM value, only contains numerical ASCII characters: the comparison fails ifnumeric nibbles of the CVMsubmitted value containsare non-numericalexpanded ASCIIto the corresponding characters. Ifcoded on one byte and the CVM valuepadding nibble contains'F' only numericalis deleted ASCII(if characterspresent). Otherwise, formatthe conversion occurscannot occur and the comparison succeedsis deemed unsuccessful;

whenIf the lengthcomparison is unsuccessful and the data value matchCVM state is exactly; not IfBLOCKED, then the comparison isCVM try successfulcounter must be decremented (by 1). In this case, if the CVM try counter mustreaches a value of '0' then the CVM state shall be reset andset to BLOCKED, otherwise the CVM state muststate shall be set to VALIDATEDINVALID_SUBMISSION.

If the comparison is unsuccessfulsuccessful, then the CVM try counter mustshall be updatedreset to the CVM try limit and the the CVM state mustshall be set to INVALID_SUBMISSIONVALIDATED.

The Retry Counter objectCVM try counter and the CVM states VALIDATED and INVALID_SUBMISSIONstate shall not conform to a transactiontransaction in progress, i.e. they shall not revert to a previous value if aa transaction in progress is aborted; If the maximum number of tries has been reached, the CVM state must be set to BLOCKED.

@param baBuffer the source byte array containing the submitted CVM value. This buffer mustMust be a global byte array. @param sOffset the offset of the submitted CVM value within source byte arraybaBuffer. @param bLength the length of the submitted CVM value. @param bFormat the format of the submitted CVM value: .FORMAT_ASCII, .FORMAT_BCD or .FORMAT_HEX. @return value indicating.CVM_SUCCESS whetherif the comparison was successful, or.CVM_FAILURE otherwise. @exception SecurityException if baBuffer is not a global byte array. Values@exception other thanNullPointerException if CVM_SUCCESSbaBuffer (0)is or null. CVM_FAILURE@exception (-1)ArrayIndexOutOfBoundsException areif reading the submitted CVM Reservedvalue would cause access of data for Future Useoutside array bounds.

The CVM value is formatted as ASCII bytes.

Note:

• If the CVM value is stored in a format other than ASCII, it is the responsibility responsibility of the interface to convert to the expectedexpected format.

The CVM value is formatted as numerical digits, coded on a nibble (4 bits) and left justified.

Note:

• If the CVM value is stored in a format other than BCD, it is the responsibility of of the interface to convert to the expectedexpected format.
• If the length of the CVM value is odd, the right most nibble ofof the CVM value value shall be high values ('F').

The CVM value is formatted as hexadecimal (binary) data.

Note:

• If the CVM value is stored in a format other than HEX, it is the responsibility of the the interface to convert to the expectedexpected format.

This defines the interface correspondinginterface allows querying and topotentially modifying the GPRegistryEntry of a singleregistry data of an Application. The Global Serviceregistered within the GlobalPlatform ApplicationRegistry.

usesEvery thisGPRegistryEntry interfaceinstance to checkan the validity ofApplication registered within the requestGlobalPlatform presentedRegistry.

byTo retrieve an on-card entity. Prior toinstance usingof this interface, an Application is requiredshall to obtain a handle toinvoke thethe GPRegistryEntryGPSystem.getRegistryEntry ofmethod.

an@since

Application by
• export invoking thefile version GPSystem1.getRegistryEntry()1: method.initial version. @since
• export file version 1.16: reviewed overall description of this interface.

This method allowsDeregisters a service aname.

Global Services ApplicationThe OPEN shall (e.g.check a CVMthat the Application) invoking this method corresponds to deregisterthis aentry, that it has the Global Service Privilege, and that the specified service name was previously uniquely registered by that same Application. If not, this method shall throw an exception (see below).

Notes: The@param OPENsServiceName the service checksname that theshall be deregistered.

A service requestingname is encoded on-card entity2 hasbytes, the Global Service Privilege1st byte identifying a family of services and is associated with this registrythe 2nd byte identifying a service entry; within that family.

The OPENGPSystem checksclass thatdefines a set of constants FAMILY_XXX (of the byte type) that may be used to build a service name is(of registeredthe short type) suitable to invoke this method as unique forshown in the requestingfollowing on-cardexamples:

• (short)((GPSystem.FAMILY_CVM<8)|0x11) entity
• (short)((GPSystem. FAMILY_HTTP_ADMINISTRATION<8)|0x00)

@paramexception sServiceName the uniqueISOException if this servicemethod is not supported or if the service name was not found or if the conditions allowing to deregister the service name are not satisfied. @exceptionsee ISOException#registerService with@see theGPSystem#FAMILY_CVM following@see reasonGPSystem#FAMILY_SECURE_CHANNEL code:@see GPSystem#FAMILY_USSM ISO7816.SW@see GPSystem#FAMILY_AUTHORITY @see GPSystem#FAMILY_CONDITIONSHTTP_ADMINISTRATION @see GPSystem#FAMILY_NOTHTTP_SATISFIEDREPORT

ThisGets method returns the Application's AID registered in the current GlobalPlatform Registry's entry. Notes: Theof OPEN checks that the requesting on-card entity has the Global Service Privilege and is associatedApplication withcorresponding to this registry entry; The OPEN checks that the service name is. registered@return asAID unique forinstance identifying the requesting on-card entity. Application @returncorresponding theto AIDthis objectentry.

ThisGets method returns all the Privileges bytesPrivilege registered inBytes of the currentApplication GlobalPlatform registrycorresponding to this entry. @param baBuffer The byte array where Privileges bytesBytes are toshall be storedwritten. @param sOffset The offset inwithin baBuffer at which to begin the Privileges byteswhere Privileges Bytes shall be written. @return sOffset + Lengthnumber of thePrivilege PrivilegesBytes written to baBuffer. @exception ArrayIndexOutOfBoundsExceptionSecurityException if storingbaBuffer is not accessible in the Privilegescaller's context e.g. bytesbaBuffer is wouldnot a global cause access outsidearray nor an array boundsbelonging orto the sOffsetcaller context. @exception NullPointerException if baBuffer is negativenull. @exception ArrayIndexOutOfBoundsException if writing Privileges Bytes would cause access of data outside array bounds.

ThisGets method returns the Life Cycle State registered inof the current GlobalPlatform RegistryApplication corresponding to this entry. @return Thethe Life Cycle State as defined in sectionof the Application corresponding 11.11to this entry.

ThisChecks method allows towhether verify if the entitythe Application corresponding to whosethis AID is provided inentry is associated with the inputspecified parametersSecurity isDomain.

registered as the associated Security Domain ofThe OPEN shall check that the specified thissdAID GPRegistryEntry. indeed Notes: identifies Thea OPEN determines ifSecurity Domain present on the SDAIDcard, is registered inand check that thethe Application current GlobalPlatformcorresponding to Registry'sthis entry as the associatedis associated with this Security Domain. If not, this method shall return false.

@param SDAID objectsdAID AID of the investigateda Security Domain. @return Truetrue if the GP RegistryApplication referencescorresponding the Securityto Domainthis as beingentry is associated with this GPRegistryEntry, or the specified Security Domain, Falsefalse otherwise.

ThisChecks method allowswhether anthe Application (e.g. a CVM Application)corresponding to verify if a given Privilege isthis registered in this GPRegistryEntryentry has the specified (e.gprivilege.

checkIf the CVMspecified Management privilege of anotheris Applicationunknown, invoking thethis method shall CVM.update()return method)false. @param bPrivilege the privilege number to verifycheck, asi.e. one defined inof the TablePRIVILEGE_XXX 6-1constants. @return Truetrue if at least the referenced Privilege is registered inApplication the GPcorresponding to Registrythis entry, or has False if the referenced Privilege is not registered in thespecified GPprivilege, Registryfalse entryotherwise.

ThisRegisters methoda service name allowsidentifying a Globalservice Services Applicationprovided by (e.gthe Application corresponding to this entry.

a CVM The Applicationspecified service name (sServiceName) to registershall be aunique among uniqueall the service identifiernames previously withinregistered in the GlobalPlatformGlobalPlatform Registry using this method. Following successful invocation of this method, Notesthis service name is known to be uniquely registered: no other Application on the card will be able to register the same service name (until this service name is deregistered (see .deregisterService)). If the service name identifies a family of service, no other Application on the card will be able to register a service of that family.

The OPEN checksshall first check that the requestingApplication invoking on-cardthis method entitycorresponds to this entry and that it has the Global ServiceService Privilege.

and is associatedThen the OPEN shall check withthat the currentspecified service name:

• is not already uniquely registered in the GlobalPlatform Registry entry; Theif OPEN checks thatthe service name identifies an entire family of services, then the requestedOPEN shall check that no service identifiername of that family is registered.
• was previously recorded for the Application matches withcorresponding to this entry (onei.e. specified as part of System Install Parameters in the INSTALL command).

If any of the Serviceabove conditions is not satisfied, this method shall throw an exception Parameter(ssee below). Otherwise, recordedthe specified service name shall be uniquely registered in the current GlobalPlatform Registry.

entry; @param ThesServiceName OPENthe service checksname that theshall be uniquely registered.

A service identifiername is notencoded already registeredon 2 asbytes, unique by any otherthe 1st byte identifying entrya family of services in and the GlobalPlatform2nd Registrybyte identifying a service within that family. If @paramthe sServiceName2nd byte is set to 0x00, the caller of this method is registering an entire family of service.

The GPSystem class defines a set of constants FAMILY_XXX (of the uniquebyte type) that may be used to build a service name (of the short type) suitable to registerinvoke this method as shown in the following examples:

• (short)((GPSystem. FAMILY_CVM<8)|0x11)
• (short)((GPSystem.FAMILY_HTTP_ADMINISTRATION<8)|0x00)

@exception ISOException withif this method is not supported or if the conditions allowing to register the following reasonservice name code:are not ISO7816satisfied.SW @see #deregisterService @see GPSystem#getService @see GPSystem#FAMILY_CONDITIONSCVM @see GPSystem#FAMILY_NOTSECURE_SATISFIEDCHANNEL @see GPSystem#FAMILY_USSM @see GPSystem#FAMILY_AUTHORITY @see GPSystem#FAMILY_HTTP_ADMINISTRATION @see GPSystem#FAMILY_HTTP_REPORT

Sets the Life Cycle state of the Application corresponding to this entry.

This method allowsenforces the Life Cycle stateState of this GPRegistryEntry totransition rules described in beCard Specification v2.2.1 section 5.

If this entry transitionedcorresponds to the Issuer Security Domain (ISD), then the OPEN shall check that the requested targettransition complies statewith Card Life Cycle State transition rules. If needed, the OPEN shall check that the Application invoking this method has the Card Lock Privilege or the Card Terminate Privilege.

Notes Otherwise, the following rules shall apply:

• AIf transitionthis requestentry corresponds to a Security Domain, then the OPEN shall check that the requested transition complies with Security Domains' Life Cycle State INSTALLEDtransition shallrules. be
• If rejected;this entry does not correspond to a Security Domain, Athen the OPEN shall check the requested transition requestcomplies towith Applications' Life Cycle State transition rules.
• If this method is invoked to transition an Application (or Security Domain) from the INSTALLED state other thanto the APPLICATION_LOCKEDSELECTABLE andstate, APPLICATION_UNLOCKEDthen the request shall be acceptedrejected. only if
• If the invoking Applicationhigh order bit corresponds(b8) of bState is set to this1, GPRegistryEntry; then Anthe Applicationcall to this method shall be ableinterpreted as an attempt to lock and shallan Application not(or beSecurity Domain), able toand other unlockbits of itself;bState shall be ignored (b7-b1).
• OnlyIf this entry corresponds to an Application with(or Security GlobalLockDomain) privilegethat oris currenly locked, then only the directly or indirectlyhigh order bit associated(b8) Securityof Domain bState ofshall be taken into account and, if it is set to 0 then the call to this GPRegistryEntrymethod shall be ableinterpreted as an attempt to lockunlock the Application (or unlockSecurity thisDomain). GPRegistryOther Entry; bits of bState shall be ignored (b7-b1).
• ThisIf this method is invoked to lock or unlock an Application (or Security Domain), then the OPEN shall fail ifcheck that thisthe Application invoking this method GPRegsitryEntryeither corresponds to this entry or has the Issuer Security DomainGlobal Lock Privilege.

@param bState the targetnew stateLife Cycle State. See Card Specification v2.2.1 section 11.1.1 for thisdetails on Life Cycle GPRegistryEntryState Coding. @returnA Truevalue of ifGPSystem.APPLICATION_LOCKED the(resp. transition0x00) ismay successful,be used to request locking (resp. unlocking) an Application or a Security Domain (other than or the ISD). @return true if the transition was successful, Falsefalse otherwise.

The GPSystemThis class exposes a subset of the behavior of the OPEN to the outside world. The OPEN implements and enforces a Card Issuer's security policy relating to these services. This OPEN classIt provides functionality at the same level as the JCRE, i.e. the "system" context with special privileges. This class is composed of static methods visible to all applets importing the globalplatform package. @since

• export file version 1.0: initial version.
• export file version 1.1: new services and/or constants added.
• export file version 1.3: new services and/or constants added.
• export file version 1.5: new services and/or constants added.
• export file version 1.6: reviewed overall description of this interface.

ThisGets methoda reference returnsto a handleCVM toinstance provided by the CVMOPEN.

interfaceSince export file version 1. 1, this Notesmethod allows looking up for CVM instances registered as Global Services by so-called Global Services Applications (i.e. Applications having the Global Service Privilege) and the following mechanism is defined to retrieve such instances:

• The OPEN searcheslooks up in the GlobalPlatform Registry for the CVMa Global Services Application that(i.e. hashaving the Global Service Service privilegePrivilege) and is uniquelythat registered a registeredGlobal Service with the specified FAMILY_CVMbCVMIdentifier and this identifier for the bCVMIdentifier.FAMILY_CVM family, or isthat uniquely registered a Global Service for the entire .FAMILY_CVM; family.
• The OPEN invokes thethen retrieves Applet.getShareableInterfaceObject()the methodcorresponding ofGlobalService the corresponding CVM Applicationinstance by invoking the Applet. OPENgetShareableInterfaceObject provides the following parameters to the method of that Global Services Application Applet.getShareableInterfaceObject()with method:the #clientAID# isparameter set to the AID of the the current applet context (i.e. the requestingone on-cardinvoking this entitymethod) and #the parameter# is parameter set to to .GLOBAL_SERVICE_IDENTIFIER;.
• The CVM Application returns theOPEN reference of thethen retrieves a Shareable Interface Object implementinginstance by invoking the GlobalService interface. OPEN invokes the GlobalService.getServiceInterface() method with the followingwith parameters:the #GPRegistryEntry#clientRegistryEntry isparameter set to the GPRegistryEntry interfaceinstance of the current applet applet context (i.e. the requestingone on-cardinvoking entitythis method), with the #sServiceName# first byte is set toto (.FAMILY_CVM and second byte to <8|bCVMIdentifier), the baBuffer isparameter set to null (indicating no buffer), and the sOffset and sLength are set to zero; .
• TheFinally, CVM Application returnsthe OPEN casts the referenceretrieved Shareable instance to the CVM interface before returning it.
• If any of the Shareableabove steps fails, Interface Object implementingthe requested CVM instance is deemed to be unavailable.

For backward compatibility, the .CVM_GLOBAL_PIN interfaceconstant correspondingcan still be used to access a Global Service registered with the bCVMIdentifier(.FAMILY_CVM<8|.CVM_GLOBAL_PIN) identifier, or uniquely registered for the entire .FAMILY_CVM family. Whether such This handlea service is thenavailable returned by OPENor not still todepends on the requestingissuer's appletpolicy. @param bCVMIdentifier identifies the requiredrequested CVM interfaceinstance. @return therequested CVM interface objectinstance, reference. or null if there is no matchingthe CVM Interface in the GlobalPlatform Registryrequested CVM instance is not available. @see #CVM_GLOBAL_PIN

ThisGets method returns the Life Cycle State of the current applet context. Notes: The OPEN locates the entry of the current applet context in the Open Platform Registry and retrieves the Life Cycle State.

@return the Life Cycle State of the current applet context. @see #APPLICATION_INSTALLED,INSTALLED @see #APPLICATION_SELECTABLE,SELECTABLE SECURITY_DOMAIN@see #APPLICATION_PERSONALIZEDLOCKED

ThisGets method returns the Life Cycle State of the card.

@return the Life Cycle State of the card card. @see #CARD_OP_READY,READY @see #CARD_INITIALIZED,INITIALIZED @see #CARD_SECURED,SECURED @see #CARD_LOCKED, LOCKED @see #CARD_TERMINATED

Gets a GPRegistryEntry instance.

This method allows anthe Application (e.g.associated awith the current CVM)applet context to access the GPget its own RegistryGPRegistryEntry entryinstance ofor the one of another Application. If no AID isthe input,aid this method providesparameter is not thenull GP Registry entry ofand does not identify the requesting Application. It returns a handleinvoking this tomethod, the GPRegistryEntry interface. OPEN Notes: shall Thecheck OPEN verifies that the requesting Applicationthat the Application invoking this method has the Global Registry privilegePrivilege. If not, or isthis method shall thereturn null.

@param Security Domain associated withaid the AID of the Application being investigated,whose GPRegistryEntry orinstance is therequested. investigatedUse Applicationnull itself. to retrieve the @paramGPRegistryEntry reqAID identifiesinstance of the requiredcurrent GPRegistryEntry interfaceapplet context. @return The GPRegistryEntry interface reference corresponding to the input AID,requested or GPRegistryEntry nullinstance if there isit no Application inwas found in the GPGlobalPlatform Registry that corresponds toand the input AID or if theApplication requesting Application is not authorizedinvoking this method is allowed to access the corresponding GP Registrythat entry. @see, AIDnull otherwise. @since export file version 1.1

This method returnsGets a handle to the SecureChannel interfaceinstance.

Notes: The OPENThis method locatesallows the entryApplication ofassociated with the current appletapplet context in theto Open Platformretrieve a RegistrySecureChannel to determine theinstance provided by application'sits associated Security Domain.

Since export file version 1.1, Thisalthough not required, this method may bebe implemented using athe similar mechanismGlobal Service asfacility, described for thein which case getCVMSecureChannel methodinstances would be registered by Security Domains as Global Services. In this case, Security Domains shall check that they only provide such SecureChannel instances to their associated Applications.

@return the SecureChannel interface object reference. @see #getCVM the GPSystem.getCVM() method for an example of how to access a Global Service.

This methodGets a returnsGlobalService a handleinstance matching tothe specified service name (sServiceName).

The serverAID parameter is optional (i.e. may be set to null) and identifies the Global Services interfaceApplication providing ofthe aservice.

The OPEN shall look for the Global Services Application. providing Notesthe service:

• TheIf the serverAID parameter is optional:null, ifthen notthe OPEN knownshall bylook for the requestingspecified on-cardservice entity,name it isamong the set toof null; uniquely Theregistered sServiceNameservice parameternames is(see mandatoryGPRegistryEntry.registerService). WhenIf the serverAIDrequested isservice name only identifies Nulla family of services, thethen the OPEN searchesshall look for a uniquely registered service name of the GlobalPlatform Registryrequested family for(the search strategy remains implementation dependent). If a matching service name is found, the Global Services Application corresponding to thisis uniquethe sServiceNameone or to this entirethat uniquely registered that service familyname.
• Otherwise, Whenif the serverAID parameter is notnot null, then the OPEN checks thatshall look in the sServiceNameGlobalPlatform Registry for the corresponding Application:
  • If the Application does not have the Global Service Privilege, then or the search is deemed to thisbe unsuccessful. entire
  • If the requested service name (or family isof service) was not previously recorded for that Application (i.e. not specified as part of System Install Parameters in the GPINSTALL Registrycommand), for thisthen the serverAID; search OPENis invokes the Appletdeemed to be unsuccessful.getShareableInterfaceObject() method of the
  corresponding

If a Global Services Application. was found, then the OPEN providesshall retrieve the followingGlobalService parameters toinstance by invoking the Applet.getShareableInterfaceObject() method: of that Global Services Application with the clientAID isparameter set to the AID of thethe current applet context (i.e. the requestingone on-cardinvoking this entitymethod) and and the parameter isparameter set to .GLOBAL_SERVICE_IDENTIFIER; . The@param serverAID AID of the Global Services Application returnsproviding the requested service, or null if the referencecaller of this method is requesting a uniquely registered service name.

@param sServiceName service name identifying a service or a family of services.

A service name is encoded on 2 bytes, the Shareable1st byte identifying Interfacea family Object implementingof services and the GlobalService2nd byte identifying a service within that interfacefamily. If Thisthe 2nd byte is handleset to 0x00, the GlobalService interface is then returned by OPENcaller of this method is requesting a toservice of the requestingspecified applet. family, but does not care exactly which service within that family.

@paramThis serverAID identifies the required Global Serviceclass defines a set of constants ApplicationFAMILY_XXX AID(of orthe isbyte null. type) @paramthat sServiceName identifies the required Global Service Service Namemay be used to build a service name or(of thethe short type) entiresuitable Serviceto invoke this method as shown in Familythe following examples:

• (short)((. FAMILY_CVM<8)|0x11)
• (short)((.FAMILY_HTTP_ADMINISTRATION<8)|0x00)

@return the GlobalService instance giving access to interface objectthe requested referenceservice, or null if the Global Services Application could not be found or did not provide a GlobalService instance. @see #GLOBAL_SERVICE_IDENTIFIER @see #FAMILY_CVM CVM @see #FAMILY_SECURE_CHANNEL @see #FAMILY_USSM @see #FAMILY_AUTHORITY @see #FAMILY_HTTP_ADMINISTRATION @see #FAMILY_HTTP_REPORT @see GPRegistryEntry#registerService @since export file version 1.1

Locks the card. This method locksshall be used to transition the card to .CARD_LOCKED Life Cycle State.

Notes: The OPEN locates theshall entry ofcheck that the currentApplication applet context in the Open Platform Registryinvoking this method has the Card Lock andPrivilege. verifiesIf thatnot, the application has thetransition card lock privilegeshall be rejected.

@return true if the card was locked, false otherwise.

This methodSets sets the historical bytes of the ATR (Answer To Reset (ATR) string.

This method only updates the ATR string that is used for the contact-based IO interface (as specified by [ISO/IEC 7816] upon power-up or cold reset. The sequenceATR ofstring used for warm reset shall remain unchanged. The new historical bytes willshall be visible onupon anext subsequent power-up or cold reset.

Notes: The OPEN locates theshall entry ofcheck that the currentApplication applet contextinvoking this inmethod has the Open Platform RegistryCard Reset Privilege and verifies that the applicationbLength is has theboth positive "Cardand Reset"lower privilegethan for16. If not, the current cardchange shall I/Obe interface;rejected.

Notes:

• The OPEN is responsible for synchronizing the length of historicalhistorical bytes in in the format character (low order Format Characternibble of T0) of the ATR string.

@param baBuffer the source byte array containing the ATR historical bytes. @param sOffset offset of the ATR historical bytes within source byte array. @param bLength the numberlength of the ATR historical bytes. @return true if ATR historical bytes were set, false otherwise.

Sets the Life Cycle state of the Application invoking this method. This method allows the applicationApplication associated with the current appletapplet context to lock itself or to change its state tofrom an application specific lifespecific cycle state orLife Cycle State to lockanother itself.application Anspecific Life applicationCycle State. An Application cannot unlock itself.

using thisThe OPEN method.shall check that @paramthe bStateApplication is currently in an applicationapplication specific lifeLife cycle stateCycle State (i.e. in the range [0x07 to.. 0x7F] and with 3its 3 low order bits set to 1), orin particular that it is not in the .APPLICATION_LOCKEDINSTALLED (0x80)state and not currently locked. If not, the change shall be rejected. @return The OPEN shall check that falsebState ifeither encodes an application specific Life Cycle State or has its high order bit (b8) set to 1: the latter case shall be interpreted as a request from the the Application to lock itself. @param bState either an application invoking this method isspecific Life Cycle State currently(i.e. lockedin the range [0x07 . . 0x7F] and with its 3 low order bits set to 1), or any value having its high order bit (b8) set to 1. A value of .APPLICATION_LOCKED may be used to request locking the Application. @return true if the operationLife isCycle State successfulof the Application was changed, false otherwise. @see #APPLICATION_INSTALLED @see #APPLICATION_LOCKED @since

• export file version 1.0: initial version.
• export file version 1.5: this method now allows the applicationapplication associated with the current applet context to lock itself.

This methodTerminates terminates the card. Notes: This method shall not be invokedused to fromtransition the Appletcard to .install()CARD_TERMINATED methodLife Cycle State.

The OPEN locates theshall entry ofcheck that the currentApplication applet context in the Open Platform Registryinvoking this method has the Card Terminate andPrivilege. verifiesIf thatnot, the application has thetransition card terminate privilegeshall be rejected.

@return true if the card was terminated, false otherwise.

The current applet context is in the Life Cycle State of LOCKED (0x80). To know ifwhether an application is locked or not, a logical AND operationoperation shall be performed between this constant and the current application lifelife cycle state.

Indicates that the required CVM interface required is the ETSI PIN App 1 (0x01). @since export file version 1.5

Indicates that the required CVM interface required is the ETSI PIN App 2 (0x02). @since export file version 1.5

Indicates that the required CVM interface required is the ETSI PIN App 3 (0x03). @since export file version 1.5

Indicates that the required CVM interface required is the ETSI PIN App 4 (0x04). @since export file version 1.5

Indicates that the required CVM interface required is the ETSI PIN App 5 (0x05). @since export file version 1.5

Indicates that the required CVM interface required is the ETSI PIN App 6 (0x06). @since export file version 1.5

Indicates that the required CVM interface required is the ETSI PIN App 7 (0x07). @since export file version 1.5

Indicates that the required CVM interface required is the ETSI PIN App 8 (0x08). @since export file version 1.5

Indicates that the required CVM interface required is a Global PIN (0x11).

Indicates the family of the HTTP Report Service Identifier (0x85). Application is not requested to expose this service through .getService(AID, short) @since export file version 1.3

This defines the interface forallows requesting a Global Services Application to provide its actual service interface. The Global Services Application uses thisfor interface to check thea Shareable Interface Object validity(SIO) ofproviding the requestactual service.

presented byTo retrieve an on-card entity. Prior toinstance usingof this interface, an Application is required to obtain a handle to the Global Services Application byshall invoking theinvoke the GPSystem.getService() method.

@since export file version 1.1

This method returns a handleGets a Shareable Interface Object to(SIO) actually providing the requested service.

interface of a Global ServicesThe Application invoking this method Application.shall set the clientRegistryEntry to its own GPRegistryEntry instance.

Note: The Global Services Application verifiesshall verify the validity of the requestrequest according to its own security policies policies for thisthe specified sServiceName and, based on the identity of the requestingand characteristics of on-cardthe entity and its characteristics as Application invoking this method as registered inby the specified clientRegistryEntry; , Onand a valid servicepossibly based on request,the data contained in the GlobalbaBuffer Servicebyte Applicationarray.

returnsIf the referencerequest is ofvalid, the Shareable Interface Global Service Application Objectreturns a SIO implementing the actual service: this Shareable InterfaceSIO Object may either be this GlobalService instance or another object. If the request is deemed to be invalid, the Global Service Services Application interfaceshall reject the request by either throwing an exception or anotherreturning null.

It is assumed that the Application invoking Javathis method Cardis aware of shareablethe interface; (extension of the Shareable interface) to which the retrieved SIO shall be casted in order to acces the service.

Notes:

• Depending on its own securityIt shall be noticed that policy,an Application having the Global ServiceRegistry Privilege could potentially invoke this method with the clientRegistryEntry parameter set to the GPRegistryEntry instance of another Application. If the Global Services Application itself has the Global Registry Privilege, it may reject an invalid service request explicitly retrieve and check the byGPRegistryEntry either throwing an exception or justinstance of the Application invoking this returningmethod, by performing the following call: nullGPSystem.getRegistryEntry(JCSystem.getPreviousContextAID()).

@param clientRegistryEntry the GP Registry entryGPRegistryEntry referenceinstance of thethe requesting on-card entityApplication.

@param sServiceName a service name identifying the requested service.

A service name is encoded on 2 bytes, the 1st byte identifying a family of services and the 2nd byte identifying a service within that family.

@paramThe baBufferGPSystem class defines a set of constants FAMILY_XXX (of the byte type) that may be used to build a service name (of the short type) suitable to invoke this method as shown in the sourcefollowing examples:

• (short)((GPSystem.FAMILY_CVM<8)|0x11)
• (short)((GPSystem.FAMILY_HTTP_ADMINISTRATION<8)|0x00)

@param baBuffer byte array containing additional parameters of the service request, potentially authentication data. Must be global byte array. @param sOffset offset of the additional request parameters within the source byte array. @param sLength length of the additional request parameters. @return the specificSIO serviceproviding interfacethe actual referenceservice, or null if the service is not available or the request was rejected. Alternatively, this method may reject the request by throwing an ISOException. @exception ISOException withif the request was rejected. Although not mandatory, it is recommended to use one of the following reason codes:

• '6A88' if the specified service was not found or is not available.
• '6982' if some security conditions are not satisfied.
• '6985' if some other conditions are not satisfied.

Alternatively, this method may reject the request by returning ISO7816null.SW_CONDITIONS_NOT_SATISFIED @exception SecurityException if the Global Services Application requires reading data from baBuffer and baBuffer is not a global byte array. @exception NullPointerException if the Global Services Application requires reading data from baBuffer and baBuffer is null. @exception ArrayIndexOutOfBoundsException if the Global Services Application requires reading data from ISO7816baBuffer and reading data would cause access of data outside array bounds.SW @see GPSystem#getService @see GPSystem#FAMILY_SECURITYCVM @see GPSystem#FAMILY_STATUSSECURE_NOTCHANNEL @see GPSystem#FAMILY_SATISFIEDUSSM @see GPSystem#FAMILY_AUTHORITY @see GPSystem#FAMILY_HTTP_ADMINISTRATION @see GPSystem#FAMILY_HTTP_REPORT

Key Access indicating key may be used by the Security Domain and anyany associated applicationApplication (0x00).

Key Access indicating key may be used by any associated applicationApplication but notnot by the Security Domain (0x02).

Key Access indicating key may be used by the Security Domain but not by any associated applicationany associated Application (0x01).

This interface handlesdefines ana method to trigger a new HTTP administration session triggering request.

The object implementing this interface shall belongTo retrieve an instance of this tointerface, the JCRE to have an Application shall use the accessGlobalService toinstance, anyif object.available, The HTTPAdministrationregistered with a service shallname verifyof (GPSystem.FAMILY_HTTP_ADMINISTRATION<8|0x00). that@see theGlobalService method@see parametersGPSystem#getService are@since

within
• export bounds andfile version all1.3: objectsinitial passedversion. in
• export as parametersfile version are1.6: accessible from thereviewed overall description of caller#sthis contextinterface. @since export file version 1.3

Request anTriggers a new administration session.

The Security Domain of the callingApplication invoking applicationthis method will handle thethe SCP81 (PSK TLS) security of the communication.

The callingApplication applicationinvoking this method will be notified of the requestresult executionof the request if it implements the interface HTTPReportListener interface.

@param triggeringParameters this bufferbyte contains thearray containing administration sessionsession triggering parameters as defined in Amendment Bparameters. @param offset offset of triggering parameters within triggeringParameters triggeringParameters. @param length length of parameters withintriggering triggeringParameters parameters. @exception java.lang.SecurityException if triggeringParameters is notnot accessible in the caller#'s context. @exception java.lang.NullPointerException if triggeringParameters is equalis to null. @exception java.lang.ArrayIndexOutOfBoundsException if offsetreading ortriggering lengthparameters would lead tocommand would cause access of data outside array bounds. @exception javacard.framework.ISOException with one of the following reason codes:

• SW_WRONG_DATA if data within triggeringParametersparameters are notnot correctly formatted.
• SW_CONDITIONS_NOT_SATISFIED if operationthe request could not bebe processed (for examplee.g. if no SCP 81SCP81 support is possible forsession the calling applicationcould be established).

An applet may implement thisThis interface in orderdefines a method to receive a notification on HTTPAdministrationupon completion request(success processing. or failure) of an HTTP Administration Session.

Such an applet shall expose the An Application that wishes to receive HTTPReportListenersuch interfacea object(s)notification through shall implement the javacard.framework.Applet.getShareableInterfaceObject(javacard.framework.AID, byte)to return an HTTPReportListener only ifinstance when the clientclientAID AIDparameter is set to null, and the parameter parameter is setset to GPSystem.FAMILY_HTTP_REPORT.

@since

• export file version 1.3: initial version.
• export file version 1.6: reviewed overall description of this interface.

Notifies the appletApplication that the requested HTTPAdministrationSessionHTTP has beenAdministration Session successfully completed or not.

The OPEN notifynotifies the AppletApplication when the HTTPAdministrationSessionHTTP Administration Session endends or when the retry policy is exhausted.

@param status With following meaning Either .HTTP_SESSION_NO_ERROR: HTTPAdministration session End (failure) or .HTTP_SESSION_ERROR: retry policy of the HTTPAdministration session is exhausted(success).

Constant notifying that the HTTPAdministartiona HTTP sessionAdministration Session failsfailed. That Theis, the retry policy of the session is exhausted and the administration sessionsession request is aborted.

Constant notifying that HTTPAdministration session Enda HTTP Administration Session ended successfully

This interface defines the interface that representsa method through which an applet methodApplication accessible through the OPENmay forward input data to theanother Application's associated Securityand Domain.retrieve The Applet class thatoutput data from that willApplication.

use the additional functionality that allows a Security DomainThis interface shall be implemented by an Application that wishes to pass data toreceive the applet and send backpersonalization data forwarded by its Applet#sassociated data personalization must implement this interfaceSecurity Domain and request outputting response data. TheIn OPEN issuch a responsiblescenario, of calling this new interface ifif the Application implements both the implementedApplication byand the Applet to Personalization personalizeinterface, otherwisethen the interface ApplicationSecurity Domain shall be called. See also section 7.3.3 ofuse the GlobalPlatform Card SpecificationPersonalization v2interface.2 - Personalization

support. @see Application @since export file version 1.2

ThisProcesses method processes Applicationapplication specific data received from another entity on the -card entity.

If this other entity is thethe Application invoking this method Application'sis associateda Security Domain, this data is the APDUthen it shall be buffer. assumed Notesthat:

• DuringBoth the invocationinBuffer theand JavaoutBuffer Card VM performsbyte arrays are aglobal context switchbyte arrays;
• The appletdata forwarded by the Security Domain is responsible fora STORE managingDATA command. The sOffset parameter locates the atomicityclass byte of its ownthe command data; and the AssLength aparameter indicates the length of the entire command (i.e. header + data field).
• The Security Domain immaterialwill ofsend back to the off-card entity the output data written by the Application Lifeto outBuffer. Cycle
• Any State can invokeexception thrown by this method will be rethrown by the Security Domain, ithence will be converted to and returned as a response status word to the off-card entity. If the exception is an ISOException, then the responsibilitystatus ofword will be the applet to ensurereason code of that itsexception. Otherwise, current Life Cycle Statea status word of is'6F00' validwill forbe returned.

Notes:

• Upon invocation of this operationmethod, the Java Card VM performs a context switch.
• As the appletApplication is not the currently selected Application, itit should not useattempt theto access transient memory of type CLEAR_ON_DESELECT when creating transientduring the processing arraysof this method.
• IfThe the method throws an ISOExceptionApplication is responsible for managing the JavaCardatomic runtime environment sends modification of its own thedata, associatedif reasonneeded. code
• As as the response statusthis method may be instead.invoked If the Exception thrown doesby a Security Domain immaterial of notthe Application's extendsinternal ISOExceptionstate, the reason codeApplication is ISO7816.SW_UNKNOWN. responsible Thefor ensuring personalizationthat its internal state is valid session remains openfor this operation.

@param inBuffer the source byte array containing theinput data. expected by theMust be a applet.global This buffer must bebyte globalarray. @param inOffset starting offset within source byteof input data arraywithin inBuffer. @param inLength length of input data. @param outBuffer the out byte array where theoutput data expected by the Off-Card Entity shall be setwritten. Must This bufferbe a shallglobal be globalbyte array. @param outOffset starting offset within outwhere output bytedata shall be written within array inBuffer. @return Thethe number of bytes setwritten to outBuffer. @exception inoutBuffer atSecurityException if outOffsetinBuffer or outBuffer is not a global byte array. @throws Exceptions thrownexception NullPointerException if areinBuffer Applicationor specificoutBuffer is null. @exception ArrayIndexOutOfBoundsException if reading intput data or writing output data would cause access of data outside array bounds.

This interface defines an interface to bebasic Secure Channel services used to manage entity authentication and protect APDU commands and responses. It is typically exposed by a Security Domain to its associated Applications.

Using an Application that may want toinstance of this interface requires delegateno knowledge of the handlingunderlying ofprotocols, entityalgorithms and secrets used to perform entity authentication and provide integrity and confidentiality of APDU securitycommands and responses, which only need to be known by the provider of the instance.

An Application that wishes to delegate such activities to its associated Security Domain shall retrieve a SecureChannel instance provided by its associated Security Domain using the GPSystem.getSecureChannel method. On some implementations, this SecureChannel instance may also be retrieved using the GPSystem.getService method.

ThisIf the card supports logical channels, this interface is designedresponsible tofor correctly offer interoperability to the Application in that it requires no knowledge handling any indication of a logical channel number present in the class byte of theAPDU mechanismscommands. usedIn particular, it shall be able to perform the authenticationverify and remove or(i.e. ofunwrap) the schemeprotection used(if forany) of an APDU security and shall allow an Application to interfacecommand without altering such indication of a logical channel correctlynumber. withUpon successful initialization of a Secure Channel Session, the implementation shall establish both a compulsory Session Security DomainLevel and a Current Security Level:

immaterial
• The compulsory Session Security Level is the Security Level negotiated during the initialization of the mechanismssession, or schemesthat shall usedapply as a minimum security requirement during the entire Secure Channel Session. Prior to using thisThe compulsory Session Security Level interface,shall anonly Applicationbe reset upon (full) termination of the Secure Channel Session.
• The Current Security Level is requiredthe security requirement that shall indeed apply to obtainAPDU commands a(and responses) during the handlesession and is initialized to its associated Securitythe same value Domain#sas SecureChannel interface object by invokingthe compulsory Session Security Level at the beginning of the GPSystemsession.getSecureChannel The Current Security Level may be subsequently updated (e.g. R-MAC or not) method.upon The SecureChannel interface shall only besuccessful processing of some commands specific to exposedthe underlying security protocol or upon successful throughinvocation of the GPSystemSecureChannelx.getSecureChannel()setSecurityLevel method. (if Insupported), all cases wherebut shall never get below the Applicationminimum passesrequirement defined by the APDUcompulsory Session Security Level. bufferThe Current Security Level, as awell as any information parameterrelating to the Secure Channel Session (except the compulsory Session Security DomainLevel), the class byteshall be reset upon abortion or termination of the APDU shallSecure Channel notSession.

See Card Specification v2.2.1 section 10.2.3 for details about abortion and termination of a Secure Channel Session.

Until it is aborted, a Secure Channel Session shall be modifiedbound to the following information:

• the Logical Channel on which it was initiated: The session only exists on the Logical Channel on which it was initiated. ThisIf an ensuresApplication thatinvokes this interface from another Logical Channel, then the Securityinterface Domainshall behave as if no Secure Channel Session was currently knowsopen but the logical channelexisting session numbershall neither be aborted nor be terminated. For resource management reasons, Ifattempts to open another Secure Channel Session from another Logical Channel (i.e. concurrently to the cardexisting supportsone(s)) logicalmay channels,be itrejected isby the implementation.
• the responsibility ofApplication that initiated the Securitysession: DomainAny call performed to correctlythis manageinterface by another Application from the logical channel information whenLogical Channel attached to the processingsession shall be rejected with an exception. For example, this may happen if this other Application somehow obtained a reference to this interface using the APDUsharing mechanism.

@since

• export file version 1.0: initial version.
• export file version 1.6: reviewed overall description of this interface.

ThisDecrypts method is used tosensitive decryptuser data located in the input buffer.

Notes: ProcessingThe this method shall complydecryption algorithm and cryptographic key used to thedecrypt rulesdata, of the Secureas well as Channelany padding Protocolmethod, implemented by the Securityare known implicitly and depend Domain; on Thethe Security Domainunderlying security implicitlyprotocol.

knowsIf the key toCurrent be used forSecurity Level is decryption. NO_SECURITY_LEVEL Theor Security Domain is implicitly aware ofthe necessary cryptographic keys are not anyavailable, padding that may be present in the then this method shall throw an exception decrypted(see below).

Otherwise, the data and this isshall be decrypted discarded. and Thethe clear text data replacesshall replace the cipheredencrypted data within the bytebaBuffer byte array. The removal removal of padding may cause the length of the clear text datadata to be shorter than the length of the cipheredencrypted data. The applet is responsible for checking the integrity of the decryptedAny failure in the decryption or padding removal process shall dataresult in an exception being thrown (see below).

Notes:

• A Secure Channel Session shall be opened andThe Application is responsible for removing application specific apadding, sensitiveif dataany. decryptionFor keyexample, shall beif the available; underlying Thissecurity methodprotocol is failsSCP if'02', a Secure Channel Sessionthen no padding method is defined and this method will not open remove any (i.epadding. Session Security
• The Level =Application is NO_SECURITY_LEVEL)responsible or iffor checking the corresponding sessionintegrity keys are not availableof the decrypted data.

@param baBuffer byte array containing the source bytedata that arrayshall be decrypted. @param sOffset offset withinof the source byte arraydata to start the decryptionthat shall be decrypted. @param sLength the numberlength of bytesthe todata decryptthat shall be decrypted. @return The length of the clear textdecrypted data, with any padding removed if a padding method is defined for the underlying security protocol. @exception ISOException with one of the following reason codes (other reason codes specific to the underlying security protocol may be returned):

• ISO7816.SW_SECURITY_STATUS_NOT_SATISFIED'6985' if a Secure Channel Session has not been openedthere is no Secure Channel Session currently open.
• ISO7816.SW_WRONG_LENGTH'6700' if the length of the data tothat shall be decrypted is not valid (e.g. underlying algorithm requires data to be block-aligned and input data are not).

@exception java.lang.SecurityException if baBuffer is not accessible inin the caller#'s context e.g. baBuffer is not a global array nor an array belonging to the caller context. @exception NullPointerException if baBuffer is null. @exception ArrayIndexOutOfBoundsException if reading user data or writing decrypted data would cause access of data outside array bounds.

ThisEncrypts sensitive user data.

If this method is used to encrypt data located innot supported by the implementation or the input buffer. underlying Notes: protocol Processingdoes this method shall comply to thenot define any sensitive data encryption rulesmechanism, of the Secure Channel Protocol implemented by theit shall do nothing and simply throw an exception Security(see Domain; below).

The Security Domain is implicitly awareencryption algorithm and cryptographic key ofused to encrypt data, as well as any padding thatmethod, are mustknown beimplicitly and applied todepend on the clearunderlying textsecurity dataprotocol.

prior to encryption according to theIf the Current Security Level is Secure.NO_SECURITY_LEVEL Channelor Protocol; the Thenecessary Securitycryptographic keys Domainare implicitlynot available, then this method shall throw an exception (see below).

knowsOtherwise, the key todata shall be usedpadded for(NOTE: encryption. depends Theon cipheredthe underlying protocol) and encrypted and the encrypted data replacesshall replace the clearclear text data within the baBuffer byte array. AThe Secure Channel Sessionaddition of padding shallmay cause the length of the encrypted data to be opened and a sensitivelonger than the length of the clear text data. encryption keyAny failure in the padding or encryption process shall beresult available; in an exception being thrown (see below).

Notes:

• ThisThe methodApplication is responsible for adding failsapplication specific padding, if aneeded. SecureFor Channelexample, Sessionif the underlying security protocol is notSCP open'02', then (i.e.no Session Security Level =padding method is defined NO_SECURITY_LEVEL)and or if the corresponding sessionthis method by itself will keysnot add any padding, which may lead to an exception being thrown (see below) if input data are not availableblock-aligned.

@param baBuffer the byte array containing the data tothat shall be processedencrypted. @param sOffset offset withinof the byte arraydata to start the encryptionthat shall be encrypted. @param sLength the numberlength of bytesthe todata encryptthat shall be encrypted. @return The length of the encrypted data. @exception ArrayIndexOutOfBoundsExceptionISOException with ifone enciphering produces data outside arrayof the following reason codes bounds.(other reason @exceptioncodes ISOException withspecific to the followingunderlying reasonsecurity protocol may be codereturned):

• ISO7816'6982' if this method is not supported by the implementation.SW_SECURITY_STATUS_NOT_SATISFIED
• '6985' if athere is no Secure Channel Session currently open.
• '6700' if the length of the data that shall be encrypted is not openvalid (e.g. underlying algorithm requires data to be block-aligned and input data are not).

@exception java.lang.SecurityException if baBuffer is not accessible inin the caller#'s context e.g. baBuffer is not a global array nor an array belonging to the caller context. @exception NullPointerException if baBuffer is null. @exception ArrayIndexOutOfBoundsException if reading user data or writing encrypted data would cause access of data outside array bounds.